home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 1 / United Public Domain Gold 1 .iso / sid2.lha / XICON.DOC < prev   
Text File  |  1994-08-04  |  22KB  |  461 lines

  1. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%  December 1989
  2.  
  3.  
  4.              XICON  --   Execute Command File from an Icon
  5.  
  6.                             Release 2.5
  7.  
  8.  
  9. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10.  
  11.    Copyright (c) 1986, 1987 , 1989 by Pete Goodeve -- All Rights Reserved
  12.  
  13.    Permission is granted to distribute this program freely, provided that
  14.    no charge is made for its use. For any commercial purposes, please
  15.    contact the author:
  16.  
  17.                   Pete Goodeve
  18.                   3012 Deakin Street #D
  19.                   Berkeley, Calif. 94705
  20.  
  21. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  22.  
  23.  
  24. With this program you can execute a file of AmigaDOS CLI commands
  25. directly from a WorkBench window, rather than from the CLI, simply by
  26. double-clicking an associated icon in the window.  A  window will be
  27. opened to display the output of the commands.  It is similar to
  28. Commodore's IconX, but has been around about two years longer and
  29. has a number of facilities that the other lacks.
  30.  
  31. This is release 2.5 of XICON.  In addition to all the features of the
  32. previous version, it now changes to the current directory automatically
  33. before running the script, and can now invoke the "EXECUTE" DOS command to
  34. run it (giving you the use of IF, THEN, and ELSE) if necessary.  You can
  35. pass other icons as parameters to EXECUTE scripts by multiple selection.
  36.  
  37.  
  38.  
  39. Basic Concepts:     The straightforward use of XICON is to have a 'project'
  40. ===============     type icon, with XICON as the Default Tool, associated
  41.                     with a file of CLI commands (a "script"): when you
  42. double-click on the icon the commands in the file will be executed.  A
  43. full-screen window is opened to display their output.  The window will
  44. remain open when the script is finished until you either click on the Close
  45. gadget or type a control-C (or -D).  The current directory when the script
  46. is entered is the same as that containing the icon.
  47.  
  48. Many changes can be rung on this basic behavior by adding "Tool Types"
  49. to the icon's info. (These ToolTypes are all treated more extensively in
  50. their own sections later.)  For example, the window can be configured to
  51. close automatically by setting the ToolType 'MODE=closewindow' in the icon.
  52. If none of the commands have any output that you need to see, set it to
  53. "'MODE=nowindow' and the program will not bother to open a window at all
  54. (any output is just thrown away).
  55.  
  56. To set the size of the window that will be opened, use the Tool
  57. Type 'WINDOW=...'.  To change its title at any point in the sequence,
  58. use 'TITLE=...'.  (These options and all the others are described in
  59. detail in their own sections below.)
  60.  
  61. You also have the option of executing commands from the ToolTypes lines
  62. of the icon itself, if you specify them with the 'CMD=...' ToolType.
  63. (There are advantages and disadvantages to this.)  You can specify
  64. additional command scripts (which will be executed before the one
  65. associated with the icon) with 'SCRIPT=...'.  This ToolType always
  66. executes the specified script directly (it doesn't invoke the DOS
  67. 'EXECUTE' command); if your script has conditional commands in it,
  68. you will need to use 'EXECUTE=...' instead.  The script attached to
  69. the icon itself will be run via EXECUTE automatically if the first
  70. character is a period.
  71.  
  72. You can include a remark to be displayed in the window with 'REM=...', or a
  73. text file with 'TEXT=...'.  You can include as many instances of these
  74. particular Tool Types as you like (unlike configuration settings such as
  75. 'MODE' or 'WINDOW'); they are processed in sequence.  The sequence may
  76. include a wait for a signal from the user with 'PAUSE'.
  77.  
  78. For some applications it may be of more use to have some file other than a
  79. script attached to the icon -- under WorkBench 1.3, in fact, an icon
  80. doesn't need any associated file at all.  If you set 'MODE=noscript' the
  81. attached file can be any type of data -- even a directory; you can operate
  82. on it if you want with commands in the ToolTypes list.  If you set
  83. 'MODE=text' it will be treated as a simple text file to be displayed
  84. a page at a time in the window.
  85.  
  86. You can take special action if the sequence has been aborted (except
  87. when you cut a test display short) -- see the description of the
  88. 'ABORT-...' Tool Types below.  You can also use the 'EXISTS=...'
  89. ToolType to see if a file exists, and abort if it doesn't.
  90.  
  91.  
  92.  
  93. Multiple Icons:     You can select more than one icon at a time if you
  94. ==============      like, by holding down the Shift key as you click on
  95.                     each. Only DOUBLE-click on the LAST selection (or use
  96. the "Open" item in the WorkBench Menu -- see "Introduction to Amiga").
  97.  
  98. The behavior in shift-select mode has changed somewhat in this version: the
  99. icons are processed in sequence from first to last, and as long as none of
  100. the attached scripts begins with a period (i.e. requires 'EXECUTE') all the
  101. ToolTypes and scripts are processed in sequence as well (and as in earlier
  102. versions); however, if any attached script DOES begin with a period, ALL
  103. the remaining icons are just taken as parameters to the script, without any
  104. further processing -- i.e. the icon names (minus the '.info' suffix of
  105. course) are passed as command line parameters to the script.  The
  106. 'EXECUTE=...' ToolType, on the other hand, does not work this way; it can
  107. never be passed parameters, though they can be included in the ToolType
  108. itself (see the section on this ToolType below).
  109.  
  110.  
  111.  
  112. Text Display:       When XICON is in the text display mode ('MODE=text' or
  113. ============        'TEXT=...') the file is displayed a window-full at a
  114.                     time, assuming a full screen window.  It will also
  115. pause if a form-feed character is encountered.  To continue, type any key
  116. or click in the bottom border of the window.  You can abort display of that
  117. file by either clicking in the Close gadget or typing control-C; it will
  118. immediately proceed to the next operation if any.  You will have to repeat
  119. the action to exit XICON if there are no more operations.  Note that this
  120. is different from the immediate exit that follows a click on the Close
  121. gadget in reponse to a PAUSE Tool Type.
  122.  
  123.  
  124.  
  125. Setup:              You can install Xicon itself in any convenient
  126. =====               directory: best is to use the 'C:' directory of your
  127.                     Workbench disk; or you could install it in a directory
  128. on the same disk as the icons.  (It doesn't need an icon of its own.  The
  129. one supplied is just for "introductory" purposes.)  Whichever directory you
  130. use, the icons that are going to invoke it must have a matching pathname as
  131. their DEFAULT TOOL (see below).
  132.  
  133. You can put an icon and its associated file in any directory ("drawer")
  134. that you can open under WorkBench.  The file must of course have the same
  135. name as the icon (without the '.info' extension the icon has tacked on).
  136. Each icon must be of type 'PROJECT' with a DEFAULT TOOL string specifying
  137. a path to the Xicon program.  If it is in the same directory, 'xicon' will
  138. suffice, otherwise you must use the complete pathname.  A full pathname
  139. always begins with the "device name", which is either an actual device
  140. (e.g. DF0: or RAM:) or an assigned name (e.g. SYS: or C:). (See the DOS
  141. manual.)  If the icons are on the same disk as Xicon, the device can be
  142. simply ":" (the colon character alone); for example, if the program
  143. 'xicon' is in the directory 'xicon' on the same disk as the icon,
  144. the default tool pathname would be:
  145.  
  146.                     :XICON/XICON
  147.  
  148. If it is in your system "C:" directory, set the entry to:
  149.  
  150.                     C:XICON
  151.  
  152.  
  153.  
  154. Command Scripts:          There are many ways to generate Command Script
  155. ===============           files with their icons.  One simple approach is
  156.                           to duplicate an already existing Xicon icon/file
  157. pair and rename it (using WorkBench Menu operations), then go to the CLI
  158. and modify the text file using whatever editor you are comfortable with. If
  159. Xicon is not in the appropriate directory, you will also have to change the
  160. Default Tool in the icon to the correct pathname (see below for how to do
  161. this).
  162.  
  163. Alternatively you can create the text file first (let's call it 'myscript'),
  164. then use the CLI to copy a suitable project icon to 'myscript.info' and
  165. modify it as necessary.
  166.  
  167.  
  168.  
  169. Modifying an icon:       All the changes you should need to make to an icon
  170. =================        (except change its appearance! -- there are a
  171.                          number of ways of doing that these days) can be
  172. done with the 'Info' item in the WorkBench Menu. Select the icon you want
  173. to modify by clicking on it, depress the right mouse button to bring up the
  174. menu, and select 'Info' from the 'WorkBench' section.  This should bring up
  175. an information window for that icon.
  176.  
  177. To set the DEFAULT TOOL, click in that gadget and type in (or edit) the
  178. string.
  179.  
  180. To enter a new TOOL TYPE, click first on the ADD gadget, then click in the
  181. string gadget and type it in.  If you want to insert it into an existing
  182. set, use the arrow gadgets on the left to move to the desired point first.
  183. You can of course edit the strings in the usual way.  Use the DEL gadget
  184. to remove a line completely.
  185.  
  186. When you are done, click in the SAVE box to preserve the changes.
  187. Note that there is a highly annoying bug in all the releases of WorkBench,
  188. until the very latest (1.3.2) where it has been finally fixed: very often
  189. the set of Tool Types you enter into the icon gets screwed up -- apparently
  190. the string terminator gets lost on some entries, causing the next string to
  191. be tagged on.  The only fix seems to be to go back to the Info, re-edit all
  192. your clobbered Tool Types, and try saving again. Eventually this should
  193. work.
  194.  
  195.  
  196.  
  197. Scripts with Conditional Commands and Parameters:   It is possible to
  198. ================================================    invoke scripts that
  199.                                                     contain conditional
  200. DOS commands (IF, ELSE, etc). To do this, Xicon needs to have the EXECUTE
  201. command available in the C: directory (as well as the RUN command, which it
  202. has always needed).  The FIRST character of a script that contains
  203. conditional commands (at least if it is the file directly attached to the
  204. icon), must be a period ".".  This may be the first character of a
  205. ".KEY..." script directive (see EXECUTE in the DOS Manual) or sometimes you
  206. can simply use a period by itself on the line.
  207.  
  208. If you intend to use EXECUTE, and don't actually have any .KEY parameters,
  209. it will probably still save you a lot of grief to simply use a dummy
  210. directive of the form:
  211.                         .K ""
  212.  
  213. where the "" supplies a null parameter that EXECUTE will ignore.  Otherwise
  214. a "<" character occurring ANYWHERE in your script (even in a comment!) will
  215. cause EXECUTE to complain "No .K directive".  [Just one more of the Amazing
  216. features of DOS...]
  217.  
  218. If the first character of an attached script is NOT a period, Xicon runs
  219. the sequence of commands directly, just as it always has.
  220.  
  221.  
  222.  
  223. MODE Setting:         You can alter the assumptions made by Xicon by
  224. ============          setting the Tool Type 'MODE'.
  225.  
  226.       'MODE=closewindow' avoids having to use control-C or the Close
  227.       gadget to terminate the program.  The window will close as soon
  228.       as all the commands have completed.
  229.  
  230.       'MODE=nowindow' tells XICON not to open any window at all.  Any
  231.       output from executing commands is simply thrown away (sent to NIL:).
  232.  
  233.       'MODE=noscript' prevents Xicon from trying to read commands from
  234.       its associated file, so this can be of any type.  This option only
  235.       makes sense if some ToolType such as 'SCRIPT=...', 'TEXT=...' or
  236.       'CMD=...' is used to supply the commands.
  237.  
  238.       'MODE=text' indicates that the associated file is text, and should
  239.       be displayed a window-full at a time.
  240.  
  241. Only one MODE entry will be recognized in the Tool Types array, so if you
  242. want more than one of the above options, you must specify them separated
  243. by the vertical-bar character, for example: 'MODE=noscript|closewindow'.
  244.  
  245.  
  246.  
  247. Modifying the Window:       You can specify the size, position and title of
  248. ====================        the window that XICON opens by setting the Tool
  249.                             Type 'WINDOW=xxx/yyy/www/hhh/Title', where xxx
  250. and yyy are the co-ordinates of the top left corner, www and hhh are width
  251. and height, and Title is the desired name for the window.  In other words
  252. this is just the string you would use to specify a 'CON:' window from the
  253. CLI, WITHOUT the 'CON:' prefix itself.
  254.  
  255.       You can't change the size or position of the window once it has
  256. been opened, but you can change its title.  Just include the Tool Type
  257. 'TITLE=title string'.  You can use this more than once in a sequence
  258. (of Tool Type commands -- see below) if you want.
  259.  
  260.  
  261.  
  262. Commands in the Icon:       Instead of a script file, you can specify
  263. ====================        commands directly in the Tool Types array of
  264.                             the icon, with the 'CMD=command string' format.
  265. (For example: 'CMD=list df1:work'.)
  266.  
  267. Include as many of these as you like.  They will be executed in sequence,
  268. but each by a separate CLI process, so you can't use a command to set
  269. parameters like stack size or current directory for the ones that follow.
  270. A Command Script file on the other hand is executed completely by one
  271. process, so settings are inherited.  Before each 'CMD=...' is executed, the
  272. current directory is set to that of the icon.
  273.  
  274. If you want to execute additional command script files before the one
  275. associated with the icon (if any), use 'SCRIPT=filename'.  As usual,
  276. 'filename' may either be the name of a script file in the same directory
  277. as the icon, or it may be the complete pathname of such a file.  These
  278. lines may be interspersed with 'CMD=..' lines (or others) and will be
  279. taken in their turn.  Again, each 'SCRIPT=..' is handled by a separate
  280. CLI process, and the current directory is set.
  281.  
  282. You can also invoke the DOS EXECUTE on any script through a ToolType entry:
  283.  
  284.         EXECUTE=scriptname arg1 arg2....
  285.  
  286. where 'scriptname' is the script file you wish to run , and 'arg1' etc
  287. are optional arguments (parameters) to pass to the script -- if it has a
  288. suitable '.KEY' directive to accept them (see your DOS manual under
  289. 'EXECUTE').
  290.  
  291. Note that -- unlike the automatic decision as to whether to use EXECUTE on
  292. an attached script (according to whether or not it begins with a period) --
  293. 'EXECUTE=...' always uses EXECUTE, while 'SCRIPT=...' never does.  (An
  294. initial period is not even required for the former, which may help some DOS
  295. shell scripts to run without modification.)
  296.  
  297.  
  298.  
  299. Console Interaction:        Any script run via EXECUTE is also run in
  300. ===================         "interactive" mode.  In other words a command
  301.                             in it that expects input from the console will
  302. wait for it properly. This was hard to arrange in earlier versions of
  303. Xicon: you had to resort to tricks like opening a special input window.
  304.  
  305. Actually a new CLI is being created for this, and terminated when done. If
  306. the script fails, it can dump you into this CLI (and you will see a
  307. standard prompt).  If this happens, simply type "endcli" to get out; you'll
  308. have to click on the close gadget as well, of course, if the icon doesn't
  309. have 'MODE=closewindow'.
  310.  
  311. Unfortunately nothing ever seems to be entirely free. If any program
  312. invoked by the script accesses the console for input, this also diverts
  313. access away (permanently) from Xicon, meaning that you can no longer
  314. close the window with control-C.  You still have the Close gadget, of
  315. course, or you can set MODE=closewindow to terminate automatically.
  316.  
  317. In some cases also it seems possible that programs run in this mode may not
  318. pick up a control-C abort themselves , so you STILL may have to use special
  319. tricks. Sorry.
  320.  
  321.  
  322.  
  323. Other Tool Types:       You have various other actions that you can
  324. ================        request with Tool Type strings.  They may be
  325.                         intermixed with the previous types.
  326.  
  327.        'TEXT=filename' displays the specified file in the window, in
  328.        the same way that 'MODE=text' does for the main file.
  329.  
  330.        'REM=text' displays the text line as a remark at that point.
  331.  
  332.        'PAUSE'  (Note -- no "="!) pauses the sequence at that point,
  333.        as if a form-feed had been encountered in a text file.
  334.        Continue by clicking in the bottom border of the window or
  335.        typing any key.  If you click in the Close gadget instead,
  336.        or type control-C, all remaining Tool Type commands will be
  337.        skipped except 'RESTORE' and those with the 'ABORT-' prefix.
  338.  
  339.        'RESTORE' is only relevant if the sequence has been aborted.
  340.        If it is is encountered it removes the abort condition;
  341.        Tool Type commands following it and the file associated
  342.        with the icon will then be executed as normal.
  343.  
  344.        'EXISTS=filename' will set the abort condition (as if the Close
  345.        gadget had been clicked or control-C typed) if the specified
  346.        file doesn't exist.
  347.  
  348.  
  349.  
  350. The 'abort' condition:    If the Close gadget is clicked or control-C
  351. =====================     typed in response to a PAUSE, or if an
  352.                           'EXISTS=...' Tool Type fails, the abort
  353. condition will be set; all further normal Tool Type commands, and
  354. execution or display of the file associated with the icon, will be
  355. suppressed.  If the 'RESTORE' Tool Type is encountered, however,
  356. normal operation will be restored.
  357.  
  358. There are a set of alternative Tool Type commands, corresponding to
  359. the normal ones but prefixed with 'ABORT-', that will ONLY be executed
  360. if the abort condition has been set.  The set is:
  361.  
  362.                 ABORT-REM=...
  363.                 ABORT-CMD=...
  364.                 ABORT-TEXT=...
  365.                 ABORT-SCRIPT=...
  366.                 ABORT-EXECUTE...
  367.                 ABORT-PAUSE
  368.  
  369. Note that the last one behaves JUST like normal PAUSE -- in other words
  370. if you click in the Continue gadget or type a key other than control-C
  371. the abort condition is REMOVED.
  372.  
  373.  
  374.  
  375. Sequence of Tool Types:     Remember the difference between the Tool Types
  376. ======================      that control the environment ('MODE=...',
  377.                             'WINDOW=...', etc.) and those that are scanned
  378. in sequence. The first appearance of each of the former will be recognized
  379. at startup -- and at startup only -- so they won't for example be affected
  380. by an abort condition. They may actually be placed anywhere in the set of
  381. Tool Types, in any order, and they will still be recognized.
  382.  
  383. The Tool Types processed at startup are:
  384.  
  385.               MODE=
  386.               WINDOW=
  387.               LOCDIR=
  388.  
  389. Those processed in sequence are:
  390.  
  391.               CMD=
  392.               REM=
  393.               SCRIPT=
  394.               EXECUTE=
  395.               TEXT=
  396.               TITLE=
  397.               PAUSE
  398.               RESTORE
  399.               EXISTS=
  400.               ABORT-...
  401.  
  402. If you misspell a Tool Type name, it will simply be ignored.
  403.  
  404.  
  405.  
  406. Finding the Directory:    Previous to version 2.5, Xicon couldn't set the
  407. =====================     current directory automatically before running a
  408.                           script, so the ToolType 'LOCDIR=filename' was
  409. provided. This is now as far as I can tell totally redundant, but it has
  410. been left available so that earlier scripts will still work.
  411.  
  412. If you include this ToolType in the icon, the specified file will be
  413. created and filled with a text string giving the complete path name of the
  414. directory containing the icon. Commands in the script can refer to this
  415. file -- which should be in a known place such as RAM: -- to take
  416. appropriate action.  The string is always enclosed in quotes, and has a
  417. newline character at the end.  DOS commands such as CD or DIR can read this
  418. string simply by redirecting their input and prompting with '?' (for
  419. commands like CD which don't have any needed output you can suppress the
  420. prompt by redirecting output to NIL:).
  421.  
  422.  
  423.  
  424. Caveats:
  425. =======
  426.  
  427.     Remember that the DOS command file "RUN" must be available in the "C:"
  428.     directory for Xicon to operate, and so must the "EXECUTE" command if
  429.     you want to run that type of script file.
  430.  
  431.     Because Xicon's method of direct script execution sets up the command
  432.     file as the input stream, the output window cannot be used as a console
  433.     unless the file is run via EXECUTE.  If a command in a direct script
  434.     needs keyboard input it must open up its own console window using I/O
  435.     redirection, e.g.:
  436.  
  437.                mycommand <CON:0/100/150/50/input
  438.  
  439.  
  440.     The initial stack size is always 4000 bytes.  You can change this in
  441.     your command script with a suitable STACK command.  Note that the STACK
  442.     gadget in the icon Info window does not have any effect.  (Except on
  443.     the stack used by Xicon itself!  I haven't investigated how much it
  444.     needs.)
  445.  
  446.     Remember that DOS won't let you use IF, SKIP, QUIT, and so on in direct
  447.     command script files.  Use the EXECUTE mode for these.
  448.  
  449.     You can use the RUN command from a command script, of course, but there
  450.     are problems with output in this situation.  In some cases, RUNning
  451.     multiple commands can result in a Guru -- apparently from output stream
  452.     "collision".  For safety, ALWAYS direct the output of RUN itself to
  453.     'NIL:', and the output of the commands RUN either to their own window
  454.     or to 'NIL:' also.  E.g.:
  455.  
  456.             RUN >NIL: mycommand > "CON:100/50/200/100/mycommand output"
  457.  
  458.  
  459.                            %%%%%%%%%%%%%%%%
  460.  
  461.